support ddtrace v6 for node > 22 - #818

Thanks for working on the per-runtime tracer split. The layer mapping (v5 for Node 18/20 and v6 for Node 22+) makes sense. I think the npm contract needs to be explicit before we rely on this for the migration. Here are concrete changes I suggest:

1. Declare the npm compatibility contract

dd-trace is still a devDependency, so changing it to v6 does not control what npm consumers install. Since the current code intentionally lets customers bring their own tracer, I suggest adding an engine and an optional peer range:

{
  "engines": {
    "node": ">=18"
  },
  "peerDependencies": {
    "dd-trace": "^5.123.0 || ^6.12.0"
  },
  "peerDependenciesMeta": {
    "dd-trace": {
      "optional": true
    }
  }
}

The root devDependency can remain ^6.12.0 for repository development. The optional peer prevents npm from automatically choosing v6 when no tracer is installed. We should also document Node 18/20 -> v5 and Node 22+ -> v6.

2.Keep v6 out of the shared npm package's runtime dependencies (already satisfied)

3. Test the actual packed npm artifact (can be a follow-up)

The container fixtures manually choose v5/v6, which proves the code works with the chosen tracer but does not test the npm package contract. I suggest building one tarball on Node 22, then installing that same tarball in a matrix:

strategy:
  matrix:
    include:
      - { node: 18, dd_trace: 5.123.0 }
      - { node: 20, dd_trace: 5.123.0 }
      - { node: 22, dd_trace: 6.12.0 }
      - { node: 24, dd_trace: 6.12.0 }
      - { node: 26, dd_trace: 6.12.0 }

Each leg should create an empty app and install the packed artifact plus the selected tracer:

npm init -y
npm install "dd-trace@$DD_TRACE_VERSION"
npm install ../datadog-lambda-js.tgz
node -e "require('datadog-lambda-js'); console.log(require('dd-trace/package.json').version)"

If metrics-only operation without a tracer remains supported, please add a tarball test with no dd-trace installed as well.

4. Report the tracer version loaded at runtime (nice-to-have)

The npm publish job currently builds with v6 and stamps that into dist/trace/constants.js. A Node 18 customer bringing v5 would therefore report v6. TracerWrapper already resolves the customer's tracer, so it can resolve the matching package metadata too:

private loadedTracerVersion = ''

const paths = ['/var/task/node_modules', ...module.paths]
const tracerPath = require.resolve('dd-trace', { paths })
this.tracer = require(tracerPath)
const packagePath = require.resolve('dd-trace/package.json', { paths })
this.loadedTracerVersion = require(packagePath).version

public get tracerVersion(): string {
  return this.loadedTracerVersion
}

Then use:

dd_trace: this.tracerWrapper.tracerVersion

instead of the build-time ddtraceVersion constant.

5. Avoid leaving tracked manifests modified (Resolved in my commit)

For Node 18/20, install_deps.sh currently rewrites package.json and may rewrite yarn.lock. Please perform the override against temporary copies and restore both files:

package_backup=$(mktemp)
lock_backup=$(mktemp)
cp package.json "$package_backup"
cp yarn.lock "$lock_backup"

restore_manifests() {
  cp "$package_backup" package.json
  cp "$lock_backup" yarn.lock
  rm -f "$package_backup" "$lock_backup"
}
trap restore_manifests EXIT

The installed tracer version can still be read from node_modules/dd-trace/package.json and passed to the layer-manifest step described above.

6. Add a release check for the manually maintained v5 pin (resolved in my commit)

DD_TRACE_V5_VERSION is separate from package.json and will not be updated by the existing dependency-update workflow. A release check could fail when it is stale:

source ./scripts/dd_trace_versions.sh
latest_v5=$(npm view 'dd-trace@5' version --json | jq -r 'if type == "array" then last else . end')

if [ "$DD_TRACE_V5_VERSION" != "$latest_v5" ]; then
  echo "dd-trace v5 pin is stale: configured=$DD_TRACE_V5_VERSION latest=$latest_v5"
  exit 1
fi

The main distinction is that the layer split is runtime-controlled, while an npm devDependency does not define customer resolution. These changes would preserve Node 18/20 npm support and make that contract testable.